package nl.jteam.jsa.core;

/**
 * Represents a search engine trasaction. All operation on the {@link DocumentManager} are done in the scope of a
 * DocumentTransaction.
 *
 * @see DocumentManager#getTransaction()
 * @author Uri Boness
 */
public interface DocumentTransaction {

    /**
     * Begins this trasaction and effectively making it active.
     */
    void begin();

    /**
     * Commits this transaction. If {@link #isRollbackOnly()} returns false, this transaction should be rolled back.
     *
     * @throws RollbackException When the trasaction was unexpectedly rolled back (e.g. when setRollbackOnly is called).
     */
    void commit() throws RollbackException;

    /**
     * Rolls back this transaction.
     */
    void rollback();

    /**
     * Marks this transaction as rollback-only. Once called this transaction will always rollback (even when calling
     * {@link #commit()}.
     */
    void setRollbackOnly();

    /**
     * Returns whether this transaction is marked as rollback-only.
     *
     * @return <code>true</code> if this transaction is marked as rollback-only, <code>false</code> otherwise.
     */
    boolean isRollbackOnly();

    /**
     * Returns whether this trasaction is active. A transaction is considered active only after the {@link #begin()} was
     * called and before the {@link #commit()} or {@link #rollback()} are called.
     *
     * @return <code>true</code> if this transaction is active, <code>false</code> otherwise.
     */
    boolean isActive();
}
